A composite control comprises a design time library and a run-time library. The design time library is the default library that defines the GUI representation of the control in the XForms Designer and the properties that can be set for the control. These properties control the actions that can be performed with the control at run time.

The run-time library is an optional library that defines the run-time behavior of the control. This library is required only if there is a run-time behavior associated with the control. The run-time options available for a control depend on the properties defined in the design time library of the control.

Basic Structure of a Design-time Type Library

A design time type library is similar to a run-time type library in terms of declaration.

Declaring the Interface

The interface of a control is defined by making it public. To do so, you must use the setPublic() method (function call) as shown below.

setPublic(Hyperlink, "mycontrols.designtime");

The above code denotes that a library calledHyperlinkis present in the mycontrols > designtime folder at<cordys-install-dir>\<your-instance>\web.

Declaring the Essential Type Libraries

All type libraries must be declared in the design time library, including the basic interface or control from which the composite control is extended. The following sample code defines the type libraries essential for the Hyperlink control.

importType("cas.xforms.designerlibrary.controls.XFormsControl"); importType("cas.xforms.designerlibrary.XFormsProperty");

As a default, every control must use XFormsProperty, which is used to manage the properties of a control.

Inheriting from a Parent Control

Every composite control must extend from a base control. By default, each control extends from XFormsControl, as shown below.

inherit(Hyperlink, XFormsControl);

However, it is possible to extend a control from any control. In the following code sample, the TextareaReadOnly is extended from the Textarea control.

inherit(TextareaReadOnly, XFormsTextarea);

For information on the controls available in Process Platform XForms that can be used as a base control, see Controls.

Define the Static Properties for a Control

The Static properties are the properties necessary for a control. The following code sample defines static properties for the Hyperlink control.

Hyperlink.propertiesCaption = "Hyperlink";

In addition to these, you can add or define any other static properties that are required for your control.

Using the Constructor

Each constructor of a composite control listens to its parent control and gets initialized. The sample code for the Hyperlink control is as follows.

function Hyperlink(designerWindow) { this.XFormsControl(designerWindow); }

The designerWindow property that is used inside the constructor is available for every composite control, by default.

Implementable Methods for Composite Controls

Every composite control follows the Interface > Implementation hierarchy, where some methods need to be implemented for the composite control. Some methods available for implementation are as follows.

The following sample code implements the isSingleton() method for the Hyperlink control such that only one Hyperlink control can be added to an XForm.

Hyperlink.prototype.isSingleton = function() { return true; }

Specifying Render Properties

Render properties denote the properties that need to be rendered on the HTML control. These properties are also defined on the run-time representation of the control. The following sample code demonstrates the implementation for the Hyperlink control.

Hyperlink.getRenderProperties = function()
{
    if (! this.renderProperties)
    {
        this.renderProperties = [
            new XFormsProperty("id", "ID", "@id"),
            new XFormsProperty("size", "Size", "@wcpforms:size"),
            new XFormsProperty("position", "Position", "@wcpforms:position"),
        ];
    }
    return this.renderProperties;
}

You can also execute or set a specific functionality when this value is set. In this case, a method to set the value is automatically looked for and called.

The following sample code sets the position of the Hyperlink control.

Hyperlink.setPosition = function(value)
{
    this.htmlElement.position = value;
}

It is also possible to extend or inherit the render properties from a parent control and add more properties to it. The following sample code for an XGrid extends from a Table control and adds its own properties as well.

if (! this.renderProperties)
{
    this.renderProperties = new Array().concat(XFormsTable.getRenderProperties());
    this.renderProperties.push(new XFormsProperty("xpathBusinessObject", "Business Object", "@xpathBusinessObject"));
    this.renderProperties.push(new XFormsProperty("useCheckboxes", "Use Checkboxes", "@useCheckboxes"));
 this.renderProperties.push(new XFormsProperty("shadeClasses", "Shade Classes", "@shadeClasses"));
}
return this.renderProperties;

If render properties of the parent control are used as is, the getRenderProperties() method need not be written for the composite control.

Specifying the HTML Template

An HTML template is defined for representing the composite control in design time. See Templates for Composite Controls for details.

Adding Properties to Control

You can specify properties for a control that are used during design time and can be accessed at run time.

You can use the following syntax to define properties for a control.

<script type="cordys/xml" id="<uniqueName>_propertiesDefinition">
    <properties>
        <property name="myProperty" description="My Property" type="select" oncontentchanged="propertyChanged" onbind="handleValueBind">
            <default>2</default>
            <values>option A:1,option B:2</values>
        </property>
        <property falsemode="both" type="task"/>
    </properties>
</script>

When you define the properties node for a control, a property sheet is associated with it. The property sheet appears when you double-click the control at design time. The property sheet displays the properties that you define in thepropertiesnode.
The unique name in the above sample code, is the value of the xfTemplate attribute in the toHTML() method in the design-time library of the composite control. If toHTML() method is not used in the design-time library, the library name must be used instead. If library name is used, then the unique name must be defined in lower case only.
Note: The toHTML() method is not available for composite controls created from existing markup. The following attributes are available for all properties defined for a control.

• name: Denotes the name of the property. The value you enter in the property sheet is set for the control. At runtime, the property is available on the control as <controlId>.<name>.
• description: Denotes the description of the property. The text value provided here, displays as a label for the property in the property sheet.
• type: Denotes the type of property. Following is the list of values supported for this attribute.

  Property Type	Controls displayed	How it works	Accessed at run time as
  id	Input	Displays an input field with id as its label. When edited, the corresponding property of the control is updated. If a control with same id already exists in the XForm, a notification message will display.	<controlId>.id
  boolean	Check box	-	<controlId>.<name>
  xml	Output with Zoom button

• Clicking the Zoom button opens the XML Editor application. If an XML is specified for the control, it displays in the XML Editor. If no request is set for the control, an empty XML displays.
• Modifying the request and closing the XML Editor updates the request on the control.
• The XML provided in the XML Editor must mandatorily have id as an attribute. The value of the id attribute displays in the output field.

  <controlId>.<name>
  select	Select box	The values node is used to populate the control.	<controlId>.<name>
  model	Select box	Displays the models available in the XForm.	<controlId>.model
  task	Check box	Selecting the check box displays the Task Part Details pane. The falsenode node is used to display options in the pane.	-
  webservice	Output with three buttons

• Select a Method button: Clicking this opens up the Select Method dialog page that displays the methods available in the current project. You can select a method and click OK.The name of the selected method displays in the output field.The SOAP Request for the selected method is generated and added to the application. It can also be viewed in the XML Editor in the XForms Designer. The value of the id attribute of the generated XML is set as <controlId>_request. This ID is set to the requestSchema property of the control, which can be used for accessing the request at run time.
• Clear Method button: Clicking this clears the property set on the control. It also deletes the request from the control and the XML Editor.
• View/Edit Request XML button: Clicking this opens the XML Editor. If a request is set on the control, it displays in the XML Editor. If no request is set for the control, an empty XML displays. Modifying the request and closing the editor updates the request on the control. The SOAP Request can also be viewed in the XML Editor in the XForms Designer. The id of the XML is set as<controlId>_request. This ID is set to the requestSchema property of the control, which is used for accessing the request at run time.

  <controlId>.requestScherma
  region	Select	Displays the Ids of all regions available in the form.	<controlId>.region
  reference	Input with zoom button	Clicking the Zoom button opens the Field Chooser dialog box that displays the response schema of the model as a tree list. To reference a node, select it in the tree list and click OK. The name of the selected node displays in the Input field. Note: The Zoom function opens the Field Chooser dialog box only when a model is selected. However, you can also enter your own value in the Input field.	<controlId>.xql
  string	Input		<controlId>.<name>

• falsemode: Denotes the Not Available Mode options to be displayed in the property sheet. The
  Not Available Mode denotes a scenario where a task involving the control is not available to the user. It applies to task property type.
  
  • If falsemode is set as both, the hide and disable options display in the property sheet of the control, for the Not Available Mode. You can select whether the control must be hidden or disabled when it is not available as a Task.
  • If falsemode is set as hide or disable, no options display in the property sheet, for the Not Available Mode. The control is by default hidden or displayed when not available as a Task.
• oncontentchanged: Denotes the method that must be called when a property value is edited. The method, when called, is supplied the following parameters.
  
  • htmlElement: The control for which the property is edited.
  • value: The edited value of the property.
  • parentWindow: The window object of the property sheet.The following is a sample property definition with the oncontentchanged attribute.

    <property description="Request" name="request"
        oncontentchanged="requestChanged" type="webservice"/>
    

    The following is a sample code for the method.

    /// When you select a new Web service [method request] in the property sheet, the requestChanged handler is invoked.
    // htmlElement- refers to the control that displays in the designer and for which the property is edited
    // value-refers to the new request that you select
    myControl.prototype.requestChanged = function(htmlElement, value, parentWindow)
    {
        // Get the runtime object.
        Var control = htmlElement.control;
    // Call a prototype method 'setDefaultValuesOnRequest' on myControl and pass the value.
        control.setDefaultValuesOnRequest(value);
    }

• Onbind: Denotes the method to be called before a value is bound to the control. The method, when called, is supplied the following parameters.
  
  • htmlElement: The control for which the property is edited.
  • value: The edited value of the property.
  • parentWindow: The window object of the property sheet.This attribute is available for Input and Select controls only. The following is a sample property definition with the onbind attribute.

    <property name="target" description="Target Frame" type="select" onbind="hideShowFrameProperties">
    <values>Frame:frame,Region:region</values>
    <property>

    The following is a sample code for the method.

    // When a value is bind to the 'target' property in the property sheet, the hideShowFrameProperties handler is invoked.
    // htmlElement- refers to the control that displays in the designer and for which the property is edited
    // value-refers to the new request that you select
    myControl.prototype.hideShowFrameProperties = function(htmlElement, value, parentWindow)
    {
        // Hide or show the Frame properties or Region properties in the property sheet.
        var propertyWindowDocument = parentWindow.document;
        if(value == "frame")
        {
            propertyWindowDocument.all["frameProperties"].show();
            propertyWindowDocument.all["regionProperties"].hide();
        }
        else
        {
            propertyWindowDocument.all["frameProperties"].hide();
            propertyWindowDocument.all["regionProperties"].show();
        }
        // Get the runtime object.
        Var control = htmlElement.control;
        // Call a prototype method 'targetChanged' on myControl and pass the value.
        Control.targetChanged(value);
    }

    
    The following nodes can be defined for a property to add additional features.

• default: Denotes the child node that is used to set the default value for a property of the control. The text value of the node displays as the default property in the property sheet. At run time, this value is available for the property of the control. The following sample code demonstrates the use of this attribute for a property of type xml.

  <default>&amp;lt;xml id=&amp;quot;sampleSchema&amp;quot;&amp;gt;&amp;lt;TreeSchema&amp;gt;&amp;lt;searchPath&amp;gt;items/&amp;lt;/searchPath&amp;gt;&amp;lt;Root&amp;gt;&amp;lt;description&amp;gt;Items&amp;lt;/description&amp;gt;&amp;lt;/Root&amp;gt;&amp;lt;/TreeSchema&amp;gt;&amp;lt;/xml&amp;gt;</default>
  

• values: Denotes the child node that is used to populate a property of typeselect. You can specify a list of comma separated description-value pairs to populate the Select control. The following sample code demonstrates the syntax to be used for this attribute.

  <values>Description A:Value A,Description B:Value B</values>
  <property name="chartType" description="Chart Type" type="select">
  <values>Three Dimensional Column:Column 3D,Two Dimensional Line:Line 2D</values>
  </property>

Adding Intellisense Options for the Control

For each composite control that you create, you can add intellisense options that must display in the Script Editor. To do so, you must specify the API (method or event) in the method and event definitions of the composite control.

Adding Methods to the Intellisense

To add methods to the intellisense, you must add them to the methods definitions in the format specified below.

< script type="cordys/xml" id="<uniqueName>_methodsDefinition"> <methods> <method name="setMapControl"> <parameter name="sControlType" /> <parameter name="sControlType" /> </method> </methods> </script>

where, the <methods> node is used to list the methods supported by the control at run time.
The unique name in the above sample code, is the value of the xfTemplate attribute in the toHTML() method in the design-time library of the composite control. If toHTML() method is not used in the design-time library, the library name must be used instead. If library name is used, then the unique name must be defined in lower case only.
Note: The toHTML() method is not available for composite controls created from existing markup. For each method, you can use the <method> node to define the method:

• name: Attribute that defines the name of the method.
• parameter: Defines the name of the parameter. It is possible to add zero or more parameters for each method or parameter. You can add prefixes to parameter names, such assfor string,Ifor integer, andbfor boolean. The parameter names defined here will display in the Intellisense at design time.
  
  Adding Event Definitions
  
  To add events to the intellisense, you must add the events to the events definition of the composite control. The events can be added as given below.

  < script type="cordys/xml" id="<uniqueName>_methodsDefinition">
  <methods>
      <method name="setMapControl">
          <parameter name="sControlType" />
          <parameter name="sControlType" />
      </method>
  </methods>
  </script>

  
  where, list of events supported by the control needs to be mentioned in <events> tag.
  The unique name in the above sample code, is the value of the xfTemplate attribute in the toHTML() method in the design-time library of the composite control. If toHTML() method is not used in the design-time library, the library name must be used instead. If library name is used, then the unique name must be defined in lower case only.
  Note: The toHTML() method is not available for composite controls created from existing markup. For each event, you can use the <event> node to define the event:

• name: Attribute that defines the name of the event.
• property: Defines the name of the property for the eventObject (of the event). It is possible to add zero or more properties for each event. The properties defined here will display in the Intellisense at design time.
  
  Adding Schema Definitions
  You can define the schema of the composite control, which will be used in the Message Map. The schema can be defined as given below.

  <script type="cordys/xml" id="<uniqueName>_schemaDefinition">
  <data>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://www.example.org/MapSchema"
      xmlns:tns="http://www.example.org/MapSchema"
      elementFormDefault="qualified">
      <xsd:element name="BusinessObject">
          <xsd:complexType>
              <xsd:all>
                  <xsd:element name="UniqueId" type="string"></xsd:element>
                  <xsd:element name="MarkerAttribute" type="string"></xsd:element>
                  <xsd:element name="Location">
                      <xsd:complexType>
                          <xsd:all>
                              <xsd:element name="Country" type="string"></xsd:element>
                              <xsd:element name="AdministrativeArea" type="string"></xsd:element>
                              <xsd:element name="SubAdministrativeArea" type="string"></xsd:element>
                              <xsd:element name="Locality" type="string"></xsd:element>
                              <xsd:element name="Thoroughfare" type="string"></xsd:element>
                              <xsd:element name="PostalCode" type="string"></xsd:element>
                          </xsd:all>
                      </xsd:complexType>
                  </xsd:element>
                  <xsd:element name="InfoWindow">
                      <xsd:complexType>
                          <xsd:all>
                              <xsd:element name="Title" type="string"></xsd:element>
                              <xsd:element name="Content" extendable="true">
                                  <xsd:complexType>
                                      <xsd:sequence>
                                      </xsd:sequence>
                                  </xsd:complexType>
                              </xsd:element>
                          </xsd:all>
                      </xsd:complexType>
                  </xsd:element>
              </xsd:all>
          </xsd:complexType>
      </xsd:element>
  </xsd:schema>
  </data>
  </script>

  where, the unique name is the value of the xfTemplate attribute in the toHTML() method in the design-time library of the composite control. If toHTML() method is not used in the design-time library, the library name must be used instead. If library name is used, then the unique name must be defined in lower case only.
  Note: The toHTML() method is not available for composite controls created from existing markup.

  Providing the Run-time Representation (XML Properties)

A run-time representation of a composite control is required if a run-time library is available for the control. For more information, see Templates for Composite Controls.

Context Menus

Each control can have a defined context menu (comprising a set of menu items), which displays when the XForm shows up. The following is a sample context menu definition for the Hyperlink control.

Hyperlink.prototype.onCreateContextMenu = function(contextMenu)
{
 contextMenu.addItem("CMenuRemoveObjects", "removeSelectedObjects()", "/cordys/wcp/theme/default/icon/action/delete.png", "Delete", null, null, "Del");
    contextMenu.addSeparator("CSep1");
    contextMenu.addItem("CMenuProperties", "showProperties()", null, "<b>Properties</b>");
}

This code creates an empty context menu and adds items and separators to it. Here, the methods are defined on the XForms Designer. If a context menu's method must be present in a composite control, then the method name must be suffixed with activeControl(). This ensures that the method calls the necessary function in the control library.

contextMenu.addItem("CMenuProperties", "activeControl().showMyProperties()", null, "<b>Properties<b>");

You can also choose to use the base class's context menu and remove the unrequired items from there.

XGrid.prototype.onCreateContextMenu = function(contextMenu)
{
    this.inherited(XGrid,"onCreateContextMenu");
    contextMenu.removeItem("CMenuLayout");
    contextMenu.removeItem("CMenuGridType");
}

Accessing parts of a Composite Control

Various methods are available for composite controls that enable you to access different parts of a control and the designer that hosts the control. The following methods are available in prototype functions of the control.

Controlling XForms Designer from the Composite Control

The method this.designerWindow() on the composite control prototype returns a handle to the XForms Designer window which hosts this context menu. Using the this.designerWindow() method, the following methods can be accessed from XForms Designer:

addScriptToForm($ID$_openApplication.toString(), "openApplication", controlID);

function $ID$_openApplication() { var newApplication = treeItem.data.cloneNode(true); application.loadAppPalette(newApplication); }

Controlling the Design-time Life Cycle

Design-time behavior of a control refers to its behavior in XForms Designer, that is its behavior from the time the control is dragged into an XForm to the time it is rendered, including the creation and saving of the control. It is possible to define the behavior of the control in design time.

The following methods can be used to define the design-time behavior of a control.